Logon Method (Session Object) 

The Logon method logs on to the MAPI system.

Syntax

objSession.Logon( [ profileName, profilePassword, showDialog, newSession, parentWindow ] )

Parameters

objSession

Required. The Session object.

profileName

Optional. A string specifying the user s logon name. To prompt the user to enter a logon name, omit profileName and set showDialog to TRUE. The default value is an empty string.

profilePassword

Optional. A string specifying the user s logon password. To prompt the user to enter a logon password, omit profilePassword and set showDialog to TRUE. The default value is an empty string.

showDialog

Optional. Boolean. If TRUE, displays a logon dialog box. The default value is TRUE.

newSession

Optional. Boolean. Determines whether the application opens a new MAPI session or uses the current shared MAPI session. If a shared MAPI session does not exist, newSession is ignored and a new session is opened. If the shared MAPI session does exist, this argument takes the following action:

parentWindow

Optional. Long (HWND). Specifies the parent window handle for the logon dialog box. A value of 0 (the default) specifies that any dialog box displayed is application modal. The parentWindow parameter is ignored unless showDialog is TRUE.

Remarks

The user must log on before your application can use most MAPI objects.

The common MAPI dialog boxes automatically handle many of the error cases that can be encountered during logon. When you call Logon and do not supply the optional profile name parameter, the Choose Profile dialog box appears, asking the user to select a profile. When the profileName parameter is supplied but is not valid, common dialog boxes indicate the error and prompt the user to enter a valid name from the Choose Profile dialog box. When no profiles are defined, the Profile Wizard walks the user through the creation of a new profile.

When your application calls the Logon method after the user has already successfully logged on, the OLE Messaging Library generates the error MAPI_E_LOGON_FAILURE.

The following methods can also invoke MAPI dialog boxes: Delete and Details methods (AddressEntry object), Options and Send methods (Message object), Resolve method (Recipient object and Recipients collection), AddressBook method (Session object).

Example

The first example displays a logon dialog box that prompts the user to enter a logon password. The second example supplies the profileName parameter and does not display the dialog box:

' from the function Session_Logon

    Set objSession = CreateObject("MAPI.Session")

    If Not objSession Is Nothing Then

        objSession.Logon showDialog:=True

    End If

' from the function Session_Logon_NoDialog

Function Session_Logon_NoDialog()

    On Error GoTo error_olemsg

    ' can set strProfileName, strPassword from a custom form

    ' adjust these parameters for your configuration

    ' create a Session object if necessary here...

    '

    If Not objSession Is Nothing Then

        ' configure these parameters for your needs...

        objSession.Logon profileName:=strProfileName, showDialog:=False

    End If

    Exit Function

error_olemsg:

    If 1273 = Err Then

        MsgBox "cannot logon: incorrect profile name or password; change global variable strProfileName in Util_Initialize"

        Exit Function

    End If

    MsgBox "Error " & Str(Err) & ": " & Error$(Err)

    Resume Next

End Function

See Also

Starting an OLE Messaging SessionXH3ESW, Logoff Method (Session Object)21I77CJ